Skip to content

Let agents call tools the app writes in Swift - #6

Merged
Juanpe merged 2 commits into
mainfrom
feat/host-tools
Oct 28, 2026
Merged

Juanpe merged 2 commits into
mainfrom
feat/host-tools

Conversation

@Juanpe

@Juanpe Juanpe commented Oct 28, 2026 •

Copy link
Copy Markdown
Owner

🎯 What

Adds host tools: HostTools grouped in a HostToolKit and passed as WorkflowExecutor(hostToolKits:). These are tools the app writes in Swift, such as one that edits the app's own state. Agent and Use a Tool steps select them by kit id, like any ToolKit.

Stacked on #5 (it uses nested fields in its tests and touches the same validation code). Review that one first; this PR's base moves to main once it merges.

🤔 Why

AgentTool can only send an HTTP request. When the action belongs to the app, for example "add two beers to the order on screen", the app had to stand up a fake server or an MCP connector and route the call back to itself, and local-only executions refused it as network access.

🛠 How it works

  • Same path as server tools. A host kit runs as an in-process ToolServerConnection through ServerToolCall and callServerTool, so the existing rules apply unchanged: the six-call limit, .readOnly / .noTools, events, traces, and "never retried, uncertain once dispatched".
  • Writes. Tools change something unless they pass changesSomething: false; those calls ask the writePolicy, which sees POST host:<kit id> with the tool and its arguments in the body.
  • Local-only. Host tools skip the network check, so local-only executions may call them. Their bodies are trusted, compiled code, like custom steps.
  • Codable. Workflows only name the kit. Bodies stay in memory and are never encoded. The Step and ToolKit JSON shapes are unchanged.
  • Validation. Preflight reports unknown host tools, a kit id used by both a ToolKit and a HostToolKit, duplicate tool names, and invalid parameter schemas.
  • One store. The executor keeps every tool set in one ToolSources value, which maps each id to a ToolSource: .requests, .server, .host, or .ambiguous when both kinds claim the id. Agents, Use a Tool, policies, recovery and validation each handle the sources with one exhaustive switch. The public init keeps separate toolKits: and hostToolKits:, since one is Codable data and the other in-memory code.

🧪 How it was tested

  • HostToolTests (ScriptedModel, no network):
    • an agent calls a write host tool with nested arguments after asking the write policy;
    • a denied write never runs the body;
    • read-only executions only offer read-only host tools;
    • local-only executions can call them;
    • Use a Tool sends typed arguments;
    • the preflight issues listed above;
    • host kits leave the recovery definition unchanged.
  • New opt-in LiveAppleTests.onDeviceModelCallsAHostTool: Apple's on-device model on macOS 27 calls addLine(product: Beer, quantity: 2) for "Two beers, please." All five live tests pass with RELAY_LIVE=1.
  • Full suite (300 tests), make check-style, make check-skill, and an iOS build of the four libraries.

✅ Checklist

  • make format and make check-style pass.
  • env -u RELAY_LIVE swift test -Xswiftc -warnings-as-errors passes.
  • Behavior is tested through ScriptedModel / StubProtocol, without live services or keys.
  • Public API changes are documented, and the relevant guide is updated.
  • User-facing changes are in CHANGELOG.md under Unreleased.
  • Breaking changes (API, behavior, Codable or platform) are called out with a migration.
  • No credentials, private data or prompts with user content in code, fixtures or logs.

📣 Notes for review

  • Additive: new types and a defaulted hostToolKits: parameter.
  • Recovery: checkpoints don't fingerprint host tool bodies, the same as custom steps. The host revision passed to start / resume covers changes to them, and the recovery definition stays byte-identical for existing checkpoints.
  • Privacy propagation: effectivePolicy now reads templates only from request kits. Before, it also read the tools of a kit that has a server, but those never run (server kits only offer the server's tools), so they no longer narrow a step's data access.
  • Validation refactor: tool checks moved into Workflow+ToolValidation.swift. validationIssues drops to 69 lines (under the 80-line error limit) and visit to complexity 20. Their three baseline entries are updated to the lower numbers rather than added.

@Juanpe
Juanpe added this pull request to stack #7 October 28, 2026 12:01
Base automatically changed from feat/nested-object-fields to main October 28, 2026 12:02
HostTools in a HostToolKit, passed as WorkflowExecutor(hostToolKits:), run
in-process through the same path as server tools: the write policy, the
tool-call limit and read-only policies apply, without network or connector.
Steps select them by kit id, so workflows stay Codable.
ToolSources maps each id to where its tools come from: requests, a server,
host tools, or an id both kinds claim. Every lookup is one exhaustive
switch, and recovery still fingerprints only the Codable kits.
@Juanpe
Juanpe merged commit 5fe32fc into main Oct 28, 2026
7 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant